Skip to main content

快速开始

本页是所有接口版本共用的账号与凭证申请入口。完成后,你将获得 AccessKey 凭证,并可换取 OAuth 访问令牌,调用第一个 V3 接口。

接入前准备​

  • 确认你所在组织的用户管理员可以登录高仙云平台。
  • 准备一个用于接收邀请和激活邮件的邮箱。
  • 确认需要调用的机器人已经绑定到对应账号,并准备好机器人序列号。
  • V3 接口只确保兼容 AIO 1.6 及以上软件版本。

第一步:成为开发者​

组织内邀请开发者​

  1. 用户管理员登录高仙云平台,进入导航栏的 IAM。
  2. 打开 用户管理,点击右上角 添加用户。
  3. 输入被邀请人的邮箱,系统角色选择 开发者,业务角色按实际需要选择。
  4. 提交邀请,确认页面显示邀请成功。

其他组织邀请开发者​

独立租户客户可以由管理员代管理其他客户组织:

  1. 在高仙云平台的 IAM 中打开 客户中心,输入并搜索需要代管理的客户名称。
  2. 在目标客户右侧进入该客户的用户管理页面。
  3. 点击右上角 + 用户,输入被邀请人的邮箱。
  4. 系统角色选择 开发者,业务角色按实际需要选择,然后提交邀请。

激活开发者账号​

被邀请的开发者打开邮箱,按照激活邮件完成账号激活,然后登录开放平台。如果还没有开发者账号,请先完成上面的邀请流程。

为已有账号增加开发者角色​

如果账号已经存在但没有开发者角色,用户管理员可以按以下步骤补充角色:

  1. 登录高仙云平台,进入 IAM > 用户管理,搜索目标账号。
  2. 点击账号右侧的编辑角色操作。
  3. 在左侧选择 开发者,将其移动到右侧的生效区域,然后点击 确定。

第二步:创建 AccessKey 并保存凭证​

开发者中心「我的 AccessKey」列表,包含 AccessKey、ClientID、说明、创建时间、过期时间和续期等操作

  1. 进入开发者中心左侧的 我的 AccessKey。
  2. 点击 创建,填写名称、描述和过期时间(支持 1 年、2 年或自定义),然后提交。

创建 AccessKey 弹窗:填写名称、描述,并选择 1 年、2 年或自定义过期时间

  1. 创建成功后,系统会同时生成 AccessKey 和应用信息。请在创建成功页面或下载内容中保存以下 4 个值:
凭证说明
AccessKeyIDAccessKey 标识,不参与 OAuth 请求。
AccessKeySecretOAuth 请求中的 open_access_key(通信密钥)。
ClientIDOAuth 请求中的 client_id。
ClientSecretOAuth 请求中的 client_secret。
无需单独创建应用

原「应用管理」功能已停止使用,新创建的 AccessKey 会自动生成应用信息(ClientID 和 ClientSecret),无需再单独创建应用。

AccessKey 列表提供 续期、更新Secret、下载Secret 和 删除 操作。凭证可能只在创建成功页面或下载内容中展示一次,请在离开页面前完成保存。

密钥安全

AccessKeySecret 和 ClientSecret 只能保存在服务端或安全的密钥管理系统中。不要把凭证提交到代码仓库、前端页面、日志或工单中。

关于存量 AccessKey

AccessKey 到期前请使用 续期 延长有效期;Secret 丢失时可通过 下载Secret 或 更新Secret 重新获取。旧的 V1 AccessKey 可以升级到 V3,但升级后 ClientID 仍为空,需要继续使用原应用管理中的 ClientID。

AccessKey 凭证只区分 V1 与 V3 两个版本,不存在 V2 版本。V2 接口属于旧版 OpenAPI 体系,使用 V1 版本 AccessKey 换取的令牌即可调用。

第三步:获取 OAuth 访问令牌​

打开左侧 认证服务 > 获取 OAuth 令牌,或直接使用下面的请求。认证接口沿用旧版地址;成功后返回 access_token、refresh_token 和 expires_in。

curl -X POST 'https://<developer-host>/gas/api/v1alpha1/oauth/token' \
-H 'Content-Type: application/json' \
-d '{
"grant_type": "urn:gaussian:params:oauth:grant-type:open-access-token",
"client_id": "<ClientID>",
"client_secret": "<ClientSecret>",
"open_access_key": "<AccessKeySecret>"
}'

请求字段说明:

字段说明
grant_type固定值 urn:gaussian:params:oauth:grant-type:open-access-token。
client_id创建 AccessKey 时生成的 ClientID。
client_secret创建 AccessKey 时生成的 ClientSecret。
open_access_key创建 AccessKey 时生成的 AccessKeySecret(通信密钥)。

令牌默认有效期为 24 小时。请根据返回的 expires_in 管理过期时间;令牌即将过期时,使用 认证服务 > 刷新 OAuth 令牌,并提交 refresh_token,无需重新授权。

第四步:调用第一个 V3 接口​

除认证接口外,V3 接口都以 /openapi/v3/ 开头,使用 POST 和 JSON 请求体,并携带 Bearer 令牌。例如,查询机器人当前状态快照:

curl -X POST 'https://<developer-host>/openapi/v3/robots/status/get' \
-H 'Authorization: Bearer <access_token>' \
-H 'Content-Type: application/json' \
-d '{
"robotSnList": ["<robot-serial-number>"]
}'

成功响应遵循统一结构 {code, msg, traceId, data},其中 code = 0 表示成功。失败时请按V3 统一错误码定位原因。状态快照不是实时数据,在线机器人会返回任务、电量、地图和位置等字段;离线机器人可能没有这些运行字段。

第五步:按业务域继续集成​

完成第一次调用后,可以按以下顺序扩展:

  1. 在 基础信息 中确认机器人和状态。
  2. 在 地图数据 中取得地图、画布、充电桩和地图资源。
  3. 在 任务与排班 > 能力与资源查询 中查询任务工作模式说明、机器人任务能力和任务资源。
  4. 在 任务与排班 中创建组合任务、排班或临时任务。
  5. 在 指令操作 中执行开始导航,并用查询指令状态/记录接口跟踪异步指令。

每个接口页面都提供在线调试面板、字段示例、响应样例和可复制的 curl。浏览器请求如果受到跨域限制,请复制 curl 到服务端或终端执行。